GitHub Pages 自定义域名开启 HTTPS
概述
GitHub Pages 默认使用 username.github.io/repo-name 格式的访问地址。通过自定义域名配置，可以使用自己的域名（如 admin.example.com）访问站点，并自动启用 HTTPS。
前提条件
- 拥有一个域名（可在阿里云、Cloudflare、NameSilo 等服务商购买）
- 项目已成功部署到 GitHub Pages
配置步骤
Step 1：GitHub Pages 添加自定义域名
- 进入仓库 → Settings → Pages
- 在 Custom domain 输入框中填写域名（如
vue3.example.com） - 点击 Save
Step 2：域名验证（TXT 记录）
- GitHub 会生成一个 TXT 记录值
- 复制该值
- 到域名服务商（如阿里云）添加 DNS 记录：
| 记录类型 | 主机记录 | 记录值 |
|---|---|---|
| TXT | _github-pages | GitHub 提供的验证值 |
- 回到 GitHub Pages 点击 Verify 验证
Step 3：配置 DNS 解析
根据域名类型选择不同的 DNS 配置：
顶级域名（如 example.com）
| 记录类型 | 主机记录 | 记录值 |
|---|---|---|
| A | @ | 185.199.108.153 |
| A | @ | 185.199.109.153 |
| A | @ | 185.199.110.153 |
| A | @ | 185.199.111.153 |
子域名（如 admin.example.com）
| 记录类型 | 主机记录 | 记录值 |
|---|---|---|
| CNAME | admin | username.github.io |
Step 4：启用 HTTPS
- DNS 配置生效后（可能需要几分钟到几小时）
- GitHub Pages 会自动检测并启用 HTTPS
- 在 Pages 设置页面勾选 Enforce HTTPS
Step 5：项目配置 CNAME 文件
在项目 public/ 目录下创建 CNAME 文件：
# public/CNAME（无扩展名，内容为自定义域名）
echo "vue3.example.com" > public/CNAME
bash
或通过 Vite 构建后手动添加。
配置验证清单
| 检查项 | 状态 |
|---|---|
| TXT 记录验证通过 | — |
| DNS A 记录 / CNAME 配置 | — |
| DNS check 显示正确 | — |
| HTTPS 自动启用 | — |
| Enforce HTTPS 已勾选 | — |
| 自定义域名可正常访问 | — |
域名服务商对比
| 服务商 | 价格 | 特点 |
|---|---|---|
| 阿里云 | 中 | 国内使用方便、中文界面 |
| Cloudflare | 低 | 免费 DNS、CDN 加速 |
| NameSilo | 低 | 价格便宜、隐私保护 |
DNS 生效时间
| 记录类型 | 生效时间 |
|---|---|
| TXT | 几分钟 |
| CNAME | 几分钟到几小时 |
| A 记录 | 几分钟到几小时 |
常见问题
| 问题 | 原因 | 解决方案 |
|---|---|---|
| DNS check 失败 | DNS 记录未生效 | 等待 DNS 传播，使用 dig 命令检查 |
| HTTPS 未启用 | DNS 尚未生效 | 等待 DNS 完全传播后重试 |
| 页面 404 | CNAME 文件缺失 | 在 public/ 下创建 CNAME 文件 |
| 域名无法访问 | DNS 配置错误 | 检查 A/CNAME 记录是否指向 GitHub |
实践要点
- 自定义域名需要先在域名服务商添加 TXT 记录验证域名所有权
- 子域名使用 CNAME 记录指向
username.github.io，顶级域名使用 A 记录 - DNS 配置生效后 GitHub 会自动启用 HTTPS 并提供免费证书
- 在项目
public/目录创建CNAME文件防止每次部署后域名重置 - DNS 传播可能需要几分钟到几小时，可通过
dig命令检查
↑